Feat/playground v2 by felixnorden · Pull Request #105 · null-shot/typescript-agent-toolkit

felixnorden · 2025-11-17T11:35:56Z

Summary

This PR introduces a complete rewrite of the playground package, transforming it from a basic MCP (Model Context Protocol) server management tool into a comprehensive AI Agent management and chat interface. The changes represent a fundamental architectural shift from server-focused management to agent-centric interaction.

Key Changes Overview

🏗️ Architecture Transformation

From: MCP server management tool with basic chat functionality
To: Comprehensive AI Agent playground with advanced chat interface and agent lifecycle management

📦 Package Structure Changes

Package Name: Retained @nullshot/playground but completely restructured
Exports: New modular export system for components, hooks, and utilities
Build System: Enhanced with tsup for library builds alongside Next.js app

🎨 UI/UX Revolution

Design System: Complete overhaul using shadcn/ui components in New York style
Components: 30+ new AI-specific components (ai-elements) for rich chat experiences
Styling: Tailwind CSS v4 with CSS variables and modern design patterns

Detailed Implementation

1. Core Architecture Changes

Agent Management System (`src/lib/agent-*.ts`)

agent-config.tsx: Centralized agent configuration management
agent-context.tsx: React context for agent state management with 285 lines of test coverage
agent-health.ts: Real-time agent health monitoring and status tracking
agent-persistence.ts: Local storage persistence for agent configurations
agent-storage.ts: Agent data storage utilities
agent-utils.tsx: Utility functions with comprehensive test suite (297 lines of tests)

New Component Architecture

AI Elements: 30+ specialized components for AI chat interfaces
- Rich message rendering (message.tsx, response.tsx)
- Interactive elements (actions.tsx, confirmation.tsx)
- Visual components (canvas.tsx, image.tsx, web-preview.tsx)
- Advanced features (chain-of-thought.tsx, reasoning.tsx, artifact.tsx)

2. Technology Stack Upgrades

Frontend Framework

Next.js: Upgraded to v15 with App Router
React: Updated to v19.1.1 with latest features
TypeScript: Strict mode with all strict flags enabled

UI/UX Enhancements

Tailwind CSS v4: Modern utility-first CSS framework
shadcn/ui: Comprehensive component library (New York style)
Radix UI: 15+ primitive components for accessibility
Framer Motion: Advanced animations and transitions
lucide-react: Modern icon library

Development Tools

Vitest: Modern testing framework with UI support
ESLint: Updated configuration with Next.js integration
TypeScript: Enhanced configuration with strict typing

3. New Features & Capabilities

Agent Management

Agent Selector: Multi-agent selection with health indicators
Agent Health Monitoring: Real-time status tracking
Agent Configuration: Flexible configuration system
Agent Persistence: Local storage for agent settings

Enhanced Chat Interface

Rich Message Rendering: Support for code blocks, images, web previews
Interactive Elements: Actions, confirmations, inline citations
Advanced Features: Chain-of-thought visualization, reasoning displays
Model Selection: Support for multiple AI models (Anthropic, OpenAI)

Developer Experience

Comprehensive Documentation: Multiple README files for different use cases
Agent Management Guide: Detailed documentation (AGENT_MANAGEMENT.md)
Testing Framework: Vitest with comprehensive test coverage
Build System: Dual build system for app and library exports

4. File Structure Changes

Added Files (150+ new files)

AI Elements: 30+ new components in src/components/ai-elements/
UI Components: Enhanced shadcn/ui components
Hooks: New React hooks for agent management
Utilities: Comprehensive utility functions
Tests: Extensive test coverage
Documentation: Multiple README and guide files
Assets: 19 avatar images for agent representation

Removed Files

Legacy Components: Old chat and MCP server management components
Outdated APIs: Removed old API routes and server management
Deprecated Styles: Replaced with new design system

Modified Files

Package Configuration: Complete overhaul of package.json
Build Configuration: Updated tsup.config.ts, tsconfig.json
Deployment: Enhanced wrangler.jsonc for Cloudflare Workers
Styling: Complete rewrite of global CSS

5. Export System

The package now provides a comprehensive export system:

// Main exports
export { PlaygroundProvider } from "./lib/exports/playground-provider"
export { Playground } from "./lib/exports/playground"
export { ChatContainer } from "./lib/exports/chat-container"

// Components
export * from "./lib/exports/components"

// Hooks
export * from "./lib/exports/hooks"

// Utilities
export * from "./lib/exports/utils"
export * from "./lib/exports/storage"

6. Testing & Quality Assurance

Test Coverage

Unit Tests: Comprehensive test suites for core functionality
Component Tests: React component testing with Testing Library
Integration Tests: End-to-end testing capabilities
Test Utilities: Custom test setup and utilities

Code Quality

TypeScript: Strict typing throughout codebase
ESLint: Comprehensive linting rules
Prettier: Code formatting consistency
Error Handling: Robust error handling with custom error types

Breaking Changes

API Changes

Complete API Redesign: Old MCP server management APIs removed
New Agent-Centric API: Focus on agent management and chat
Export Changes: New modular export system

Configuration Changes

Removed: Old configuration files and settings
New: Agent-specific configuration system
Migration: Manual migration required for existing implementations

Dependency Changes

Major Version Updates: Next.js, React, TypeScript upgrades
New Dependencies: 20+ new packages for enhanced functionality
Removed Dependencies: Old MCP-specific packages

Migration Guide

For Existing Users

Review New Architecture: Understand the agent-centric approach
Update Dependencies: Ensure compatibility with new versions
Migrate Configuration: Use new agent configuration system
Update Imports: Use new export system
Test Thoroughly: Validate functionality with new system

For New Users

Follow Setup Guide: Use setup-chat.md for initial setup
Review Documentation: Read AGENT_MANAGEMENT.md for detailed guidance
Explore Examples: Check showcase examples for implementation patterns

allenwyma · 2025-11-18T04:25:52Z

AGENTS.md

We should be using pnpm, we mostly reference this in our docs

@felixnorden yarn is still mentioned here

allenwyma · 2025-11-18T04:28:44Z

AGENTS.md

allenwyma · 2025-11-18T08:36:50Z

packages/playground/README.md

-    </PlaygroundProvider>
-  );
-}
+yarn dev


we should remove the others to stay in line with using pnpm across

felixnorden · 2025-11-18T14:44:52Z

Good shout, I think the doc generation picked up some stale Yarn docs

…

On Tue, Nov 18, 2025 at 10:52 AM Allen Wyma ***@***.***> wrote: ***@***.**** requested changes on this pull request. ------------------------------ In AGENTS.md <#105 (comment)> : > +- Test files: *.test.ts + +## Error Handling +- Use custom error classes from utils/errors.ts +- Always provide meaningful error messages +- Use logger.ts for consistent logging +- Handle dry-run mode in all mutating operations + +## Testing +- Use vitest with globals +- Place tests alongside source files +- Use .test.ts extension +- Mock filesystem with memfs where needed + +## Development Practices +- Use yarn for package management We should be using pnpm, we mostly reference this in our docs ------------------------------ In AGENTS.md <#105 (comment)> : > +- Write tests for all functionality +- Use Wrangler for deployments to Cloudflare Workers + +## Project Structure +- `packages/`: Contains all project packages + - `mcp/`: Main MCP implementation for Cloudflare Workers + - `test-utils/`: Utilities for testing +- `examples/`: Contains example implementations + - `crud-mcp/`: Example CRUD application using MCP framework + - `simple-prompt-agent/`: Example agent with only a prompt for chatting +- Main package: packages/mcp/src/index.ts +- MCP Server implementation: packages/mcp/src/mcp/server.ts +- Example application: examples/crud-mcp/src/index.ts + +## Development Workflow +1. Install dependencies at root level: `yarn install` same here ------------------------------ In packages/playground/README.md <#105 (comment)> : > - showHeader={true} - className="h-full" - /> - </div> - </div> - ); -} - -export default function App() { - return ( - <PlaygroundProvider config={{ /* your config */ }}> - <CustomChat /> - </PlaygroundProvider> - ); -} +yarn dev we should remove the others to stay in line with using pnpm across — Reply to this email directly, view it on GitHub <#105 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFKCPQX4TJYB44AWDGQK5HT35L255AVCNFSM6AAAAACMKMQ6ZSVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTINZVGQYDQMJSGQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

allenwyma · 2025-11-20T07:52:46Z

AGENTS.md

@felixnorden yarn is still mentioned here

Adding in status indicator for available agents and graceful errors when the call fails through toasters.

github-actions · 2025-11-20T16:35:38Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-5238ef3

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

github-actions · 2025-11-21T09:58:07Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-ba2f74f

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

github-actions · 2025-11-24T09:24:48Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-d06e40d

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

github-actions · 2025-11-24T09:49:30Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-dd44772

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

github-actions · 2025-11-25T22:37:51Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-e7fbf64

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

github-actions · 2025-11-25T22:45:04Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-e7df852

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

github-actions · 2025-11-26T02:04:18Z

🐳 Preview MCP Toolbox Docker Image Built

Image: ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Tags:
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105
ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105-bc35fdd

Usage:

# Pull the preview image
docker pull ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

# Run the MCP Toolbox server
docker run -p 11990:11990 \
  -e PROXY_ID=preview-toolbox-105 \
  -e MCP_SERVER_HOST=host.docker.internal:6050 \
  --add-host host.docker.internal:host-gateway \
  -v $(pwd)/data:/app/data \
  ghcr.io/null-shot/typescript-agent-tookit/mcp-toolbox:pr-105

Health Check:

curl http://localhost:11990/health

Note: Preview images are automatically cleaned up after 7 days.

Disturbing · 2026-01-15T13:10:26Z

This was superseded by #111

felixnorden linked an issue Nov 17, 2025 that may be closed by this pull request

Open-Source Agent Chat UI Component #62

Open

allenwyma suggested changes Nov 18, 2025

View reviewed changes

allenwyma suggested changes Nov 20, 2025

View reviewed changes

AGENTS.md Outdated

Copy link

Contributor

allenwyma Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@felixnorden yarn is still mentioned here

Disturbing and others added 10 commits November 20, 2025 09:17

Initial commit for playground v2.

cd72e5a

feat: add status indicator of agent status

adfc469

Adding in status indicator for available agents and graceful errors when the call fails through toasters.

fix: ignore of lib folder inside src

49646a1

feat: add in provider and context management for package consumption

5bf9899

fix: type issues

04c0a10

fix: type issues and exports

6ef6542

chore: add AGENTS.md for agentic dev work

7c9e9a5

chore: exports, builds, and package dep updates

5a9379c

chore: replace incorrect occurrences of 'yarn' with 'pnpm'

f54959f

chore: sync up with main and update ai-elements components

e587993

felixnorden force-pushed the feat/playground-v2 branch from 95cdbba to e587993 Compare November 20, 2025 10:16

fix: yarn mentioned

52d4c43

fix: build issue from GH actions

40ad3f0

fix: add import React statement and exports

0014a92

fix: add react import statement in missing files

e142db1

fix: cot component breaking build

be798b1

fix: react ref

a06c6a2

chore: clean up types and sync up react deps

f602a59

Disturbing closed this Jan 15, 2026

Disturbing deleted the feat/playground-v2 branch January 15, 2026 13:10

Conversation

felixnorden commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes Overview

🏗️ Architecture Transformation

📦 Package Structure Changes

🎨 UI/UX Revolution

Detailed Implementation

1. Core Architecture Changes

Agent Management System (src/lib/agent-*.ts)

New Component Architecture

2. Technology Stack Upgrades

Frontend Framework

UI/UX Enhancements

Development Tools

3. New Features & Capabilities

Agent Management

Enhanced Chat Interface

Developer Experience

4. File Structure Changes

Added Files (150+ new files)

Removed Files

Modified Files

5. Export System

6. Testing & Quality Assurance

Test Coverage

Code Quality

Breaking Changes

API Changes

Configuration Changes

Dependency Changes

Migration Guide

For Existing Users

For New Users

Uh oh!

allenwyma Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

allenwyma Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

allenwyma Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

allenwyma Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

felixnorden commented Nov 18, 2025 via email

Uh oh!

allenwyma Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 20, 2025

Uh oh!

github-actions bot commented Nov 21, 2025

Uh oh!

github-actions bot commented Nov 24, 2025

Uh oh!

github-actions bot commented Nov 24, 2025

Uh oh!

github-actions bot commented Nov 25, 2025

Uh oh!

github-actions bot commented Nov 25, 2025

Uh oh!

github-actions bot commented Nov 26, 2025

Uh oh!

Disturbing commented Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

felixnorden commented Nov 17, 2025 •

edited

Loading

Agent Management System (`src/lib/agent-*.ts`)